.TH std::mersenne_twister_engine 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::mersenne_twister_engine \- std::mersenne_twister_engine

.SH Synopsis
   Defined in header <random>
   template<

       class UIntType, std::size_t w, std::size_t n, std::size_t m,
   std::size_t r,                                                         \fI(since C++11)\fP
       UIntType a, std::size_t u, UIntType d, std::size_t s,
       UIntType b, std::size_t t, UIntType c, std::size_t l, UIntType f

   > class mersenne_twister_engine;

   mersenne_twister_engine is a random number engine based on Mersenne Twister
   algorithm. It produces high quality, but not cryptographically secure, unsigned
   integer random numbers of type UIntType on the interval \\(\\scriptsize {[0,2^w)}\\)[0,
   2w
   ).

.SH Template parameters

                         The result type generated by the generator. The effect is
   UIntType            - undefined if this is not one of unsigned short, unsigned int,
                         unsigned long, or unsigned long long.
   w                   - the power of two that determines the range of values generated
                         by the engine
   n                   - the degree of recurrence
   m                   - the middle word, an offset used in the recurrence relation
                         defining the state
   r                   - the number of bits of the lower bit-mask, also known as the
                         twist value
   a                   - the conditional xor-mask, i.e. the coefficients of the
                         rational normal form twist matrix
   u, d, s, b, t, c, l - the 1^st to 7^th components of the bit-scrambling (tempering)
                         matrix
   f                   - the initialization multiplier

   If any of the following restriction is violated, the program is ill-formed:

     * m is in [1, n].
     * The following expressions are all true:

     * w >= 3
     * w >= r
     * w >= u
     * w >= s
     * w >= t
     * w >= l
     * w <= std::numeric_limits<UIntType>::digits
     * Given (1u << w) - 1u as w1, the following expressions are all true:

     * a <= w1
     * b <= w1
     * c <= w1
     * d <= w1
     * f <= w1

   Generator properties

   The size of the states of mersenne_twister_engine is n, each of them consists of a
   sequence X of n values of type result_type. \\(X_j\\)X
   j stands for the \\(j\\mod n\\)j mod nth value (starting from 0) of X.

   Given the following bitwise operation notations:

     * \\(\\mathsf{bitand}\\)bitand, built-in bitwise AND.
     * \\(\\mathsf{xor}\\)xor, built-in bitwise XOR.
     * \\(\\mathsf{lshift}\\)lshift, built-in bitwise left-shift.
     * \\(\\mathsf{rshift}\\)rshift, built-in bitwise right-shift.

   The transition algorithm of mersenne_twister_engine (\\(TA(x_i)\\)TA(x
   i)) is defined as follows:

    1. Concatenate the upper w - r bits of \\(X_{i-n}\\)X
       i-n with the lower r bits of \\(X_{i+1-n}\\)X
       i+1-n to obtain an unsigned integer value Y.
    2. Let y be \\(a \\cdot (Y\\ \\mathsf{bitand}\\ 1)\\)a·(Y bitand 1), and set \\(X_i\\)X
       i to \\(X_{i+m−n}\\ \\mathsf{xor}\\ (Y\\ \\mathsf{rshift}\\ 1)\\ \\mathsf{xor}\\ y\\)X
       i+m−n xor (Y rshift 1) xor y.

   The generation algorithm of mersenne_twister_engine (\\(GA(x_i)\\)GA(x
   i)) is defined as follows:

    1. Let \\(z_1\\)z
       1 be \\(X_i\\ \\mathsf{xor}\\ ((X_i\\ \\mathsf{rshift}\\ u)\\ \\mathsf{bitand}\\ d)\\)X
       i xor ((X
       i rshift u) bitand d).
    2. Let \\(z_2\\)z
       2 be \\(z_1\\ \\mathsf{xor}\\ (((z_1\\ \\mathsf{lshift}\\ s)\\mod 2^w)\\ \\mathsf{bitand}\\
       b)\\)X
       i xor (((X
       i lshift s) mod 2w
       ) bitand b).
    3. Let \\(z_3\\)z
       3 be \\(z_2\\ \\mathsf{xor}\\ (((z_2\\ \\mathsf{lshift}\\ t)\\mod 2^w)\\ \\mathsf{bitand}\\
       c)\\)X
       i xor (((X
       i lshift t) mod 2w
       ) bitand c).
    4. Let \\(z_4\\)z
       4 be \\(z_3\\ \\mathsf{xor}\\ (z_3\\ \\mathsf{rshift}\\ l)\\)z
       3 xor (z
       3 rshift l).
    5. Deliver \\(z_4\\)z
       4 as the result (i.e. \\(GA(x_i)=z_4\\)GA(x
       i)=z
       4).

   Predefined specializations

   The following specializations define the random number engine with two commonly used
   parameter sets:

   Defined in header <random>
   Type               Definition
                      std::mersenne_twister_engine<std::uint_fast32_t,
                                                   32, 624, 397, 31,
                                                   0x9908b0df, 11,
   mt19937 \fI(C++11)\fP                                 0xffffffff, 7,
                                                   0x9d2c5680, 15,
                                                   0xefc60000, 18, 1812433253>
                      32-bit Mersenne Twister by Matsumoto and Nishimura, 1998
                      std::mersenne_twister_engine<std::uint_fast64_t,
                                                   64, 312, 156, 31,
                                                   0xb5026f5aa96619e9, 29,
   mt19937_64 \fI(C++11)\fP                              0x5555555555555555, 17,
                                                   0x71d67fffeda60000, 37,
                                                   0xfff7eee000000000, 43,
                                                   6364136223846793005>
                      64-bit Mersenne Twister by Matsumoto and Nishimura, 2000

   Nested types

   Type        Definition
   result_type UIntType

   Data members

   constexpr size_t word_size                   w
   \fB[static]\fP                                     \fI(public static member constant)\fP
   constexpr size_t state_size                  n
   \fB[static]\fP                                     \fI(public static member constant)\fP
   constexpr size_t shift_size                  m
   \fB[static]\fP                                     \fI(public static member constant)\fP
   constexpr size_t mask_bits                   r
   \fB[static]\fP                                     \fI(public static member constant)\fP
   constexpr UIntType xor_mask                  a
   \fB[static]\fP                                     \fI(public static member constant)\fP
   constexpr size_t tempering_u                 u
   \fB[static]\fP                                     \fI(public static member constant)\fP
   constexpr UIntType tempering_d               d
   \fB[static]\fP                                     \fI(public static member constant)\fP
   constexpr size_t tempering_s                 s
   \fB[static]\fP                                     \fI(public static member constant)\fP
   constexpr UIntType tempering_b               b
   \fB[static]\fP                                     \fI(public static member constant)\fP
   constexpr size_t tempering_t                 t
   \fB[static]\fP                                     \fI(public static member constant)\fP
   constexpr UIntType tempering_c               c
   \fB[static]\fP                                     \fI(public static member constant)\fP
   constexpr size_t tempering_l                 l
   \fB[static]\fP                                     \fI(public static member constant)\fP
   constexpr UIntType initialization_multiplier f
   \fB[static]\fP                                     \fI(public static member constant)\fP
   constexpr UIntType default_seed              5489u
   \fB[static]\fP                                     \fI(public static member constant)\fP

.SH Member functions

.SH Construction and Seeding
   constructor      constructs the engine
   \fI(C++11)\fP          \fI(public member function)\fP
   seed             sets the current state of the engine
   \fI(C++11)\fP          \fI(public member function)\fP
.SH Generation
   operator()       advances the engine's state and returns the generated value
   \fI(C++11)\fP          \fI(public member function)\fP
   discard          advances the engine's state by a specified amount
   \fI(C++11)\fP          \fI(public member function)\fP
.SH Characteristics
   min              gets the smallest possible value in the output range
   \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP
   max              gets the largest possible value in the output range
   \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP

.SH Non-member functions

   operator==                compares the internal states of two pseudo-random number
   operator!=                engines
   \fI(C++11)\fP                   \fI(function)\fP
   \fI(C++11)\fP(removed in C++20)
   operator<<                performs stream input and output on pseudo-random number
   operator>>                engine
   \fI(C++11)\fP                   \fI(function template)\fP

.SH Notes

   The N^th consecutive invocation of a default-constructed engine is required to
   produce the following value:

                      N   The random engine type The value to produce
                    10000 std::mt19937           4123659995
                    10000 std::mt19937_64        9981545732273789042

   This is to guarantee that the random engine is conforming to the standard (see
   N1398).


// Run this code

 #include <cassert>
 #include <random>

 int main()
 {
     std::mt19937 gen32;
     std::mt19937_64 gen64;

     gen32.discard(10000 - 1);
     gen64.discard(10000 - 1);

     assert(gen32() == 4123659995);
     assert(gen64() == 9981545732273789042ull);
 }
